/******************************************************************************
 * Copyright (c) 2025 Author. All Rights Reserved.
 *
 * All Rights Reserved.
 *
 * @file ec_bsp_temp_humi_xxx_handler.h
 *
 * @par dependencies
 * - <Deriver_Layer>.h
 * - stdbool.h
 * - stdint.h
 * 
 * @author aether
 *
 * @brief Provide the HAL APIs of temperature and humidity sensor handler
 * and corresponding coperations.
 *
 * Processing flow:
 *
 * Call directly.
 *
 * @version V1.0 2025-08-25
 *
 * @note 1 tab == 4 space!
 *
 *****************************************************************************/

#ifndef __EC_BSP_TEMP_HUMI_XXX_HANDLER_H__ /* Avoid repeated inclusion */
#define __EC_BSP_TEMP_HUMI_XXX_HANDLER_H__ 

//******************************* Includes **********************************//
#include "ec_bsp_aht21_driver.h"

#include <stdint.h>
#include <stdbool.h>
#include <stdio.h>

//******************************* Defines **********************************//
#define AHT21_HANDLER_DEBUG

//******************************* Typedefs **********************************//
typedef enum {
  TEMP_HUMI_OK              = 0,    /* Operation completed successfully   */
  TEMP_HUMI_ERROR           = 1,    /* Run-time error without case matched*/
  TEMP_HUMI_ERRORTIMEOUT    = 2,    /* Operation failed with timeout      */
  TEMP_HUMI_ERRORRESOURCE   = 3,    /* Resource not available             */
  TEMP_HUMI_ERRORPARAMETER  = 4,    /* Parameter error                    */
  TEMP_HUMI_ERRORNOMEMORY   = 5,    /* Out of memory                      */
  TEMP_HUMI_ERRORISR        = 6,    /* Reserved May check the caller      */
  TEMP_HUMI_RESERVED = 0x7FFFFFFF
} temp_humi_status_t;

typedef enum {
  TEMP_HUMI_EVENT_TEMP = 0,
  TEMP_HUMI_EVENT_HUMI,
  TEMP_HUMI_EVENT_BOTH
} temp_humi_xxx_event_data_type_t;

typedef struct
{
  float                   *temperature;   /* Temperature Reference       */
  float                   *humidity;      /* Humidity Reference          */
  uint32_t                lifetime;       /* Lifetime of data            */
  uint32_t                timestamp;      /* Timestamp of event          */
  temp_humi_xxx_event_data_type_t type;   /* The Data mode               */
  void (*pfcallback)(float *, float *);   /* The callback function       */
} temp_humi_xxx_event_t;

//***************************** Interface Structs ****************************//
typedef struct
{
  void (*os_delay_ms)(uint32_t const ms);           /* Delay Interface        */
  temp_humi_status_t (*os_queue_create)(            /* Queue_Create inter     */
                        uint32_t const item_num,
                        uint32_t const item_size, 
                        void ** const queue_handle);

  temp_humi_status_t (*os_queue_put)(void * const queue_handle, /* Queue_Send Inter */
                                     void * const item, 
                                     uint32_t timeout);

  temp_humi_status_t (*os_queue_get)(void * queue_handle, /* Queue_Recv inter */
                                     void *msg, uint32_t timeout);
} temp_humi_handler_os_interface_t;

typedef struct
{
  iic_driver_interface_t    *iic_driver_interface;
  timebase_interface_t      *timebase_interface;
  temp_humi_handler_os_interface_t *os_interface;
  yield_interface_t         *yield_interface;
} temp_humi_handler_all_input_arg_t;


//***************************** Classes ****************************//

typedef struct temp_humi_handler_private_data temp_humi_handler_private_data_t;

/* Handler Class Bsp Handler */
typedef struct bsp_temp_humi_xxx_handler
{
    /* Interface passed to driver layer */
    timebase_interface_t            *timebase_interface;
    iic_driver_interface_t          *iic_driver_interface;
    yield_interface_t               *yield_interface;

    /* Inerface from OS layer           */
    temp_humi_handler_os_interface_t    *os_interface;

    /* Instance of driver instance     */
    bsp_aht21_driver_t              *paht21_instance;

    /* Interface of event queue         */
    void                            *event_queue_handle;

    /* Private data                     */
    temp_humi_handler_private_data_t    *pprivate_data;

    /* Timestamp of last temperature reading */
    uint32_t                        last_temp_tick;

    /* Timestamp of last humidity reading */
    uint32_t                        last_humi_tick;
}bsp_temp_humi_xxx_handler_t;


//***************************** APIs ****************************//

/**
 * @brief A thread function that handles the temperature and humidity events.
 *
 * This function continuously checks for temperature and humidity updates and
 * sends them to the event queue. It also updates the last temperature and 
 * humidity.
 */
void temp_humi_handler_thread(void *argument);

/**
 * @brief Initializes the temperature and humidity handler instance.
 *
 * This function takes in a handler instance and input 
 * arguments to initialize the temperature and humidity handler. It sets up the
 * neccessary interafaces, creates a queue for handling events, and Initializes
 * the last temperature and humidity timestamps.
 *
 * @param handler_instance A pointer to the temperature and humidity 
 *                         handler instance.
 * @param input_arg A pointer to the input arguments containing the 
 *                  required interfaces.
 */
temp_humi_status_t bsp_temp_humi_xxx_handler_inst(
            bsp_temp_humi_xxx_handler_t * handler_instance,
            temp_humi_handler_all_input_arg_t * input_arg);

/**
 * @brief Reads the temperature and humidity from the AHT21 sensor
 *
 * This function sends an event to the AHT21 to read the temperature and 
 * humidity. When the temperature and humidity data is ready, the
 * callback function or provided pointers for temp. & humi. will be updated.
 *
 * @param[in] event A pointer to the event made by the caller
 *
 * @return An 8-bit signed integer representing the status of the event passed.
 *         - 0: Successfully queued in the handler.
 *         - Non-zero: Failed to pass.
 */
temp_humi_status_t bsp_temp_humi_xxx_read(temp_humi_xxx_event_t *event);

#endif /* __EC_BSP_TEMP_HUMI_XXX_HANDLER_H__ */

